(SST) ShlWAPI.pas Version 1.08

Developer Reference
(SST)ShlWAPI SHMessageBoxCheck Function
Displays a message box with a check box (or another control) that provides a means to the user to suppress the dialog.
Scope
Global (i.e. this function can be called/accessed from code in any unit that includes/uses (SST)ShlWAPI.pas).
Syntax
function SHMessageBoxCheck(wndh : HWND; pszText : LPCSTR; pszCaption : LPCSTR; uType : UINT; iDefault : Integer; pszRegVal : LPCSTR) : Integer;
Parameters
wndh [in] The handle of the owner window of the dialog.
pszText [in] A pointer to a zero-terminated string containing the information, error, or other text, the dialog should display to the user.
pszCaption [in] The text (in form of a pointer to a zero-terminated string) that should appear in the dialog box's title bar. If this parameter is NIL, the default title "Error!" (or the UI language's equivalent) is shown.
uType [in] A combination of bit-flags that determines the dialog's behaviour and which buttons and icons are added to the dialog. This should be a combination of the flags that determine the following message box attributes:
  1. A flag that determines which buttons are added to the dialog. This should be restricted to one of the following (but, see remarks, below):
    MB_OK The function displays a dialog with an "Ok" (or the UI language's equivalent) button.
    MB_OKCANCEL The function displays a dialog with an "Ok" and a "Cancel" (or the UI language's equivalents) button.
    MB_YESNO The function displays a dialog with a "Yes" and a "No" (or the UI language's equivalents) button.
  2. A flag that determines if, and which icon is shown in the dialog.
    MB_ICONINFORMATION,
    MB_ICONASTERISK
    A dialog including an icon denoting that information of lesser importance is displayed. The icon is typically a circle enclosing a lower case i.
    MB_ICONQUESTION The function displays a dialog with an icon suggesting that unequivocal user response is required. Typically, this is a question mark ("?") enclosed in a circle.
    MB_ICONEXCLAMATION,
    MB_ICONWARNING
    The icon displayed by the dialog symbolizes that the user should take conscious notice of the message in the dialog before closing it. Typically, this is an icon similar to traffic signs that warn drivers of imminent dangers. These signs are commonly yellow trianles with a black exclamation mark.
    MB_ICONHAND,
    MB_ICONERROR
    The icon is typically a stop sign or red circle enclosing a large x.
iDefault [in] A signed, 32-bit integer value the function should return to indicate that the user has opted to suppress the dialog.
pszRegVal [in] The name of the registry value under which the function should store whether or not the message box should be displayed.
Return Values
If the function succeeds, it returns the value of the button pressed to close the dialog or the value specified in iDefault. The latter value is also returned if the dialog is not displayed due to the user having previously opted to suppress the dialog. If the function fails, for example, due to an invalid parameter, it returns -1.
Remarks
Although Microsoft emphasizes that SHMesssageBoxCheck only supports a subset of the flags of the MessageBox function, and specifying flags not listed/documented above, may lead to unpredictable results, the tests we conducted under Windwos 2003 Server (with SP 2) and Vista (with SP 1) confirm these statements only partially, in that the results may be unpredictable when executed under different Windows versions and/or compatibility settings , but not, that only the subset of flags described above is supported, as is demonstrated by the following screen shot.
MessageBocCheck Dialog (Fig. 2.1.2.3.26.1.0.1) Fig. 2.1.2.3.26.1.0.1
The registry value specified in pszRegVal is written to the following key: HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\DontShowMeThisDialogAgain. Both, the value and the key, are created automatically if they don't exist.
The value is a string value, into which the function simply writes "NO" (without the quotation marks) once the dialog is closed and the "Don't show this dialog again"- check box's state is checked. However, the function does not provide any means to restore the initial settings. It is therefore good practice to implement some form of user interface and functionality that results in the dialog being displayed again.
This is achieved by either of two methods:
  1. Replacing the "NO" in the registry value specified in pszRegVal by "YES" (without the quotation marks).
  2. Deleting the value specified in pszRegVal.
This function is exported by name as of ShlWAPI.dll version 6.0 under Vista, but according to the declaration and documentation it is supported as of ShlWAPI.dll 5.0 under Windows 2000. However, the accompanying documentation did/does not provide any information on the ordinal(s) by which function(s) can be accessed in versions pror to Vista.
SHMessageBoxCheckA is accessible as ordinal 185, SHMessageBoxCheckW as ordinal 191, down to, at least Windows 98 SE, as we were surprised to find out. The following screen shot is the German, Windows 98 SE dialog version, displayed under Windows Vista, using ShlWAPI.dll version 5.00.2614.3500, from one or our original Windows 98 SE setup disks. The dialog is stored as resource id 4608 in the Win98 SE ShlWAPI.dll file.
MessageBocCheck Dialog (Fig. 2.1.2.3.26.1.0.2) Fig. 2.1.2.3.26.1.0.2
Example
PROCEDURE TForm4.TestShlWAPISHMessageBoxCheck(Sender : TObject); //Existence as ordinal 185 tested and confirmed under //Windows 2003 (with SP 2) VAR wndhandle : HWND; VAR messagetext : STRING; VAR wcharmsgtxt : WideString; VAR msgboxtitle : STRING; VAR wchardlgtitle : WideString; VAR msgboxtype : UINT; VAR defretval : INTEGER; VAR registryvalstr : STRING; VAR wcharregvalstr : WideString; VAR apiretval : INTEGER; VAR newinfoline : STRING; BEGIN wndhandle := 0; messagetext := ''; wcharmsgtxt := ''; msgboxtitle := ''; wchardlgtitle := ''; msgboxtype := 0; defretval := 0; registryvalstr := ''; wcharregvalstr := ''; apiretval := 0; newinfoline := ''; wndhandle := Handle; messagetext := 'Hello World !' + #13 + #10 + 'ShlWAPI function test completed.'; //Under Windows 2003 and later, it is not necessary to //append a question such as the following to the message box's text, //a text to the same effect is already added to the dialog by Windows //" + #13 + #10 + 'Always show this message ?';" msgboxtitle := 'SHMessageBoxCheck Test'; //The following line sets the "Ok" button as the default button //(i.e. the question "In the future, do not show me this dialog box" //is answered with "Ok" if the user closes the dialog by pressing Enter/Return). //However, only the state of the check box has any influence on whether the //the dialog is shown again or not. //To return to the initial behaviour of the app, set the string in the //registry value "TestShlWAPIFunctions3{9F430225-F4CB-4A7E-B717-0C118D8FAC69}", under //"HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\DontShowMeThisDialogAgain" //to "YES", or simply delete the value. msgboxtype := MB_OKCANCEL OR MB_DEFBUTTON1 OR MB_ICONINFORMATION; defretval := $FFFF; registryvalstr := 'TestShlWAPIFunctions3' + '{9F430225-F4CB-4A7E-B717-0C118D8FAC69}'; apiretval := SHMessageBoxCheck(wndhandle, PChar(messagetext), PChar(msgboxtitle), msgboxtype, defretval, PChar(registryvalstr)); newinfoline := 'SHMessageBoxCheck returned ' + IntToStr(apiretval) + ' (0x' + IntToHex(apiretval, 8) + ')'; Memo1.Lines.Add(newinfoline); msgboxtype := MB_ABORTRETRYIGNORE OR MB_DEFBUTTON3 OR MB_ICONERROR; //Combine bit 29, indicating a non-system (i.e. app) specific error with //an arbitrary, unique value, specific to this particular dialog or class/group of dialogs. defretval := $20000000 OR $8080; //messagetext := 'Tests the veracity of the Microsoft doc. on this function !' + #13 + #10 + //'This message box should be ignored.'; wcharmsgtxt := 'If this message is displayed, SHMessageBoxCheckW is exported as ordinal 191.' + #13 + #10 + 'This message box should be ignored.'; wchardlgtitle := msgboxtitle; //registryvalstr := 'TestShlWAPIFunctions3' + '{81EE5244-6596-4154-BCCB-6F6E6970A7F0}'; wcharregvalstr := 'TestShlWAPIFunctions3' + '{81EE5244-6596-4154-BCCB-6F6E6970A7F0}'; //apiretval := SHMessageBoxCheck(wndhandle, PChar(messagetext), PChar(msgboxtitle), // msgboxtype, defretval, PChar(registryvalstr)); apiretval := SHMessageBoxCheckW(wndhandle, PWChar(wcharmsgtxt), PWChar(wchardlgtitle), msgboxtype, defretval, PWChar(wcharregvalstr)); newinfoline := 'SHMessageBoxCheck returned ' + IntToStr(apiretval) + ' (0x' + IntToHex(apiretval, 8) + ')'; Memo1.Lines.Add(newinfoline); Memo1.Lines.Add(''); END;
Requirements
Unit: Declared and imported in (SST)ShlWAPI.pas
Library: (SST)ShlWAPI.dcu/(SST)ShlWAPI.obj
Unicode: Implemented as ANSI (SHMessageBoxCheck and SHMessageBoxCheckA) and Unicode (SHMessageBoxCheckW) functions.
Min. ShlWAPI.dll version according to MS SDK doc.: 5.0
Min. ShlWAPI.dll version based on SST research: 5.0
Min. OS version(s) according to Microsoft SDK doc.: Windows 2000, Windows 2000 Server, Windows XP, Windows Server 2003
Min. OS version(s) according to SST research.: Windows 98 SE, Windows 2000
See Also
ShellMessageBox.
 
Windows APIs: SHMessageBoxCheck, ShellMessageBox, MessageBox, MessageBoxEx.


Document/Contents version 1.00
Page/URI last updated on 07.12.2023
 
Copyright © Stoelzel Software Technologie (SST) 2010 - 2017
Suggestions and comments mail to:
webmaster@stoelzelsoftwaretech.com